<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xml:lang="en">
<head>
<meta http-equiv="content-type" content="application/xhtml+xml; charset=UTF-8"/>
<title>README - Google Search Appliance XHTML Stylesheet</title>
<style type="text/css">
/* <![CDATA[ */
body { color: #000; background: #fff; }
/* ]]> */
</style>
</head>

<body>

<h1 id="top">README</h1>

<h2>Google Search Appliance XHTML Stylesheet</h2>

<p>
The <em>Google Search Appliance XHTML Stylesheet</em> defines a user interface for your Google Search Appliance that conforms to modern web standards including XHTML 1.0 Strict, XHTML Mobile Profile (XHTML-MP) and CSS 2.1. It generates well-formed, valid markup and is accessible in a variety of browsers and presentation modes. (<a href="http://www.webstandards.org/learn/faq/" title="Frequently Asked Questions - The Web Standards Project">Learn more about web standards</a>.)
</p>

<h2>Table of Contents</h2>

<ul>
  <li><a href="#features">Features</a></li>
  <li><a href="#requirements">System Requirements</a></li>
  <li><a href="#files">What's Included</a></li>
  <li><a href="#install">How To Install</a></li>
  <li><a href="#linked-style">Linked vs. Embedded Style</a></li>
  <li><a href="#handheld-exclusive">Handheld-Exclusive Mode</a></li>
  <li><a href="#onebox">A Note About OneBox and XHTML</a></li>
  <li><a href="#caveats">Caveats and Known Issues</a></li>
  <li><a href="#credits">Credits and Thanks</a></li>
</ul>

<h3 id="features">Features</h3>

<ul>
  <li>12% size reduction from original XSLT</li>
  <li>28-68% reduction from original markup (using optional style library)</li>
  <li>Generated XHTML is well formed, valid, and separate from presentation</li>
  <li>Screen, print, and handheld media support for the most common presentation modes</li>
  <li>Pages are readable and accessible even with style disabled</li>
  <li>Numeric accesskey navigation of search results (optional)</li>
  <li>Screen and handheld presentation consistent with existing Google design</li>
  <li>Print style only displays content necessary for printing</li>
  <li>Embedded search results style is minimized depending on presentation</li>
  <li><a href="#handheld-exclusive">Handheld-exclusive</a> mode minimizes markup and style even further (optional)</li>
  <li><a href="#linked-style">Linked style library</a> for improved bandwidth usage (optional)</li>
</ul>

<p>
In handheld-exclusive mode, pages are further condensed and optimized for viewing on handheld devices. The WAP 2.0 compliant interface preserves Google Search Appliance features relevant to enterprise search while obeying many of the paradigms set forth by <a href="http://www.google.com/mobile/">Google Mobile Search</a>.
</p>

<h3 id="requirements">System Requirements</h3>

<ul>
  <li>Google Search Appliance running software version 4.6.2.S.22 or later</li>
  <li>A browser (user agent) capable of parsing and viewing XHTML documents</li>
  <li>A WAP 2.0 compliant device is required for browsing XHTML Mobile Profile documents</li>
</ul>

<p>The <em>Google Search Appliance XHTML Stylesheet</em> has been road-tested and tire-kicked in the following user agents:</p>

<ul>
<li><a href="http://www.caminobrowser.org/">Camino 1.0</a></li>
<li><a href="http://www.mozilla.com/firefox/">Firefox 1.5</a></li>
<li><a href="http://www.microsoft.com/ie/">Internet Explorer 6 and 7b3</a></li>
<li><a href="http://www.freedomscientific.com/fs_products/JAWS_HQ.asp">JAWS 7.10</a></li>
<li><a href="http://lynx.browser.org/">Lynx 2.8.4 and 2.8.5</a></li>
<li><a href="http://browser.netscape.com/">Netscape 7.2</a></li>
<li><a href="http://www.opera.com/">Opera 8.5 and 9.01</a></li>
<li><a href="http://mini.opera.com/">Opera Mini</a></li>
<li><a href="http://www.apple.com/safari/">Safari 2.0.4</a></li>
</ul>

<h3 id="files">What's Included</h3>

<ul>
  <li><code>README.html</code> - this file</li>
  <li><code><a href="EXTRAS.html">EXTRAS.html</a></code> - browser screen shots, example pages, and the style library</li>
  <li><code><a href="gsa-xhtml.en.xslt">gsa-xhtml.en.xslt</a></code> - xhtml stylesheet transformation</li>
  <li><code><a href="onebox-xhtml.en.xslt">onebox-xhtml.en.xslt</a></code> - OneBox module stylesheet transformation</li>
  <li><code><a href="EXTRAS.html#examples">examples/</a></code> - example pages</li>
  <li><code><a href="EXTRAS.html#screenshots">screenshots/</a></code> - browser screen shots</li>
  <li><code><a href="EXTRAS.html#style">style/</a></code> - linked style library (optional)</li>
</ul>

<h3 id="install">How To Install</h3>

<p>
The Google Search Appliance provides support for multiple front end user interfaces to the same search engine. We leverage that feature to add XHTML and XHTML-MP support:
</p>

<ol>
  <li>Add a new <em>Front End</em> using your Google Search Appliance's Admin Console. See the <a href="https://support.google.com/enterprise/doc/gsa/4x/help/serve_frontends.html">documentation</a> on the Google Enterprise support site for details on how to do this. Alternatively use the context sensitive help link in the <em>Serve -&gt; Front Ends</em> section of your Admin Console.</li>

  <li>Modify the new <em>Front End</em> by importing the supplied stylesheet transformation, <code>gsa-xhtml.en.xslt</code>. See the <a href="https://support.google.com/enterprise/doc/gsa/4x/help/serve_output_xslt.html">documentation</a> for details on how to do this. Alternatively select <em>Edit</em> for the new <em>Front End</em> and, on the <em>Format</em> tab, use the context sensitive help link for the <em>XSLT Stylesheet Editor</em>.</li>

  <li>Adjust XSLT variables to taste. Also configure <a href="#linked-style">linked style</a> or configure <a href="#handheld-exclusive">handheld exclusive</a> modes.</li>

  <li>Use the Admin Console's <em>Test Center</em> to sanity check that the stylesheet and <em>Front End</em> have been set up correctly. If you view frame source for the search page proper, you should see <code>XHTML</code> in the <code>DOCTYPE</code> line (instead of <code>HTML</code>).</li>

  <li>Publish the search link to your new <em>Front End</em> for all of your users:

  <ol>
    <li>Open a browser and navigate to your Google Search Appliance.</li>
    <li>Copy the (rewritten) link from your browser address bar and paste into a text editor.</li>
    <li>Replace the values of the "client" and "proxystylesheet" parameters with the name of your new <em>Front End</em>.</li>
  </ol>

  We recommend having a default page on a separate web server redirect to this link so that your users only need to remember (or bookmark) the simpler address (e.g.,  <em>http://www.acme.com/search</em>).
  </li>
</ol>

<h3 id="linked-style">Linked vs. Embedded Style</h3>

<p>
By default, the Search Appliance embeds CSS appropriate for each request. To further improve performance, you may optionally link to the CSS instead. This allows style to be cached and save even more bandwidth. To configure:
</p>

<ol>
  <li>Copy the <code>style</code> directory (included) to your web server of choice.</li>
  <li>Set the variable <code>style_include_prefix</code> to a URL pointing to your new directory. Include the trailing slash.</li>
  <li>Change the variable <code>style_include</code> from <code>0</code> to <code>1</code> to enable linking.</li>
</ol>

<h3 id="handheld-exclusive">Handheld-Exclusive Mode</h3>

<p>
In this mode, the XHTML and CSS sizes are reduced even further, to the point of supporting only handheld media. Enable by editing the XSLT as follows:
</p>

<ol>
  <li>Set the variable <code>media</code> to <code>handheld</code>.</li>
  <li>Comment out the <code>xsl:output</code> element referencing the <code>XHTML 1.0 Strict</code> Document Type Definition.</li>
  <li>Uncomment the <code>xsl:output</code> element referencing the <code>XHTML Mobile 1.0</code> Document Type Definition.</li>
</ol>

<p>
(Steps two and three are required until XSLT 2.0 support is provided.)
</p>

<h3 id="onebox">A Note About OneBox and XHTML</h3>

<p>
Typical <a href="http://code.google.com/enterprise/documentation/oneboxguide.html">Google OneBox for Enterprise</a> modules come packaged with their own XSLT to define the display of the OneBox section of the search results page. In most cases the resultant markup may <em>not</em> be well-formed and valid XHTML, nor styled for multiple presentation modes. To help remedy this try the following for each of your OneBox modules:
</p>

<ol>
  <li>Create a duplicate OneBox module with a different name but otherwise similar settings.  This will be your XHTML/standards-friendly version of the original OneBox module.</li>
  <li>Replace the XSLT in the new module with that in the given <code>onebox-xhtml.en.xslt</code> stylesheet transformation.</li>
  <li>Assign this new OneBox module to your mobile <em>Front End</em>.</li>
  <li>Customize the XSLT to recapture the look and feel intended by the OneBox author while remaining consistent with screen, print and handheld display design principals.</li>
</ol>

<h3 id="caveats">Caveats and Known Issues</h3>

<ul>
  <li>Google Desktop integration is not provided.</li>
  <li>To help ensure markup validity, OneBox module result sets should be enclosed by <code>&lt;tr&gt;&lt;td&gt;</code>.</li>
  <li>Cached and text version page validity is not guaranteed.</li>
  <li>Only the http scheme has been tested (not db or anything else).</li>
  <li>Developers using collections will want to copy the collection list from a newly-edited default stylesheet and integrate into the mobile stylesheet. Use the format illustrated in the <code>collection_menu</code> template (and remove the example "default_collection" and "googleenterprise" entries once finished). To maintain well-formed, valid markup, do not alter the template's structure. (Leave the trailing comma at the end of each list in the <code>collection_menu</code> template.)</li>
</ul>

<h4 id="caveats-handheld">Handheld Media-specific Notes</h4>

<ul>
  <li>Onebox results display is not vertically restricted for handheld media. Please be kind.</li>
  <li>Duplicate directory filtering is not reflected by indenting (handheld media). This is intentional.</li>
  <li>KeyMatch link display does not use <code>http://</code>. This is intentional as some mobile devices may otherwise treat them as additional links.</li>
  <li>Advanced Search is not enabled.</li>
  <li>Result dates are not displayed by default. (Some mobile devices may otherwise treat them as phone numbers!)</li>
  <li>Feel free to customize the XSLT but it is recommended that handheld-exclusive settings for stylesheet variables remain unchanged.</li>
</ul>

<h3 id="credits">Credits and Thanks</h3>

<p>The <em>Google Search Appliance XHTML Stylesheet</em> was developed for Google Enterprise by <a href="http://www.joesapt.net/">Joe D'Andrea</a> using the following tools:</p>

<ul>
  <li><a href="http://www.adiumx.com/">Adium</a></li>
  <li><a href="http://www.browsercam.com/">BrowserCam</a></li>
  <li><a href="http://www.cynthiasays.com/">Cynthia Says</a></li>
  <li><a href="http://www.entropy.ch/software/macosx/#testxslt">TestXSLT</a></li>
  <li><a href="http://macromates.com/">TextMate</a></li>
  <li><a href="http://validator.w3.org/">W3C Markup Validation Service</a></li>
  <li><a href="http://jigsaw.w3.org/css-validator/">W3C CSS Validation Service</a></li>
</ul>

<p>Thanks are due to the following people for their generosity, advisement, and support:</p>

<ul>
  <li>From <a href="http://googleenterprise.blogspot.com/">Google Enterprise</a> - Matt Glotzbach, Jeff Ragusa, Kristin Shevis, and Kevin Smith</li>
  <li><a href="http://www.plasticmind.com/">Jesse Gardner</a></li>
  <li><a href="http://www.456bereastreet.com/">Roger Johansson</a></li>
  <li><a href="http://www.strangematter.net/">Vincent Murphy</a></li>
  <li><a href="http://webstandardsgroup.org/mail/">The Web Standards Group Discussion List</a></li>
</ul>

<p>Last, but not least, thanks to:</p>

<ul>
  <li>Anyone who ever wrote a book or article about standards-based web development or accessibility.</li>
  <li><em>You</em> for downloading and trying this out!</li>
</ul>

</body>
</html>
